home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #2 / Monster Media No. 2 (Monster Media)(1994).ISO / prog_c / ems4c.zip / EMM4C.DOC < prev    next >
Text File  |  1994-05-15  |  35KB  |  1,142 lines
  1.  
  2.  
  3.                                    EMM Library
  4.  
  5.  
  6.                                 For the C Language
  7.  
  8.  
  9.                                       (EMM4C)
  10.  
  11.  
  12.  
  13.                                  USERS MANUAL
  14.  
  15.  
  16.  
  17.  
  18.  
  19.                                   Version 1.0
  20.  
  21.                                  July 24, 1993
  22.  
  23.  
  24.  
  25.  
  26.                         This software is provided as-is.
  27.                  There are no warranties, expressed or implied.
  28.  
  29.  
  30.  
  31.  
  32.                               Copyright (C) 1993
  33.                               All rights reserved
  34.  
  35.  
  36.  
  37.                               MarshallSoft Computing, Inc.
  38.                               Post Office Box 4543
  39.                               Huntsville AL 35815
  40.  
  41.                               205-881-4630 Voice / FAX
  42.                               205-880-9748 Support BBS
  43.  
  44.  
  45.  
  46.                                        _______
  47.                                   ____|__     |                (R)
  48.                                --|       |    |-------------------
  49.                                  |   ____|__  |  Association of
  50.                                  |  |       |_|  Shareware
  51.                                  |__|   o   |    Professionals
  52.                                -----|   |   |---------------------
  53.                                     |___|___|    MEMBER
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.         EMM4C Users Manual                                     Page 1
  61.                               C O N T E N T S
  62.  
  63.  
  64.  
  65.  
  66.  
  67.          Chapter                                                   Page
  68.  
  69.          1.0 Introduction..............................................3
  70.              1.1 Distribution Files....................................3
  71.              1.2 Compiling the Library.................................4
  72.              1.3 User Support..........................................4
  73.              1.4 ASP Ombudsman.........................................4
  74.              1.5 Installation..........................................5
  75.          2.0 The EMM4C Library.........................................6
  76.          3.0 EMM4C Library Functions...................................7
  77.              3.1 emmInit...............................................7
  78.              3.2 emmDone...............................................8
  79.              3.3 emmPages..............................................9
  80.              3.4 emmAlloc.............................................10
  81.              3.5 emmFree..............................................11
  82.              3.6 emmLock..............................................12
  83.              3.7 emmUnlock............................................13
  84.              3.8 emmError.............................................14
  85.          4.0 EMM4C Error Codes........................................15
  86.          5.0 The EMM4C Test Driver....................................16
  87.          6.0 Legal Issues.............................................17
  88.              6.1 Registration.........................................17
  89.              6.2 License..............................................17
  90.              6.3 Warranty.............................................17
  91.          7.0 Revision History.........................................18
  92.          8.0 Other MarshallSoft Computing Products for C..............18
  93.              8.1 The Personal Communications Library for C............18
  94.              8.2 The Personal Protocol Library for C..................19
  95.              8.3 The LZW Data Compression Library for C...............19
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.         EMM4C Users Manual                                     Page 2
  121.          1.0 Introduction
  122.  
  123.  
  124.          The  EMM4C  library  is  an expanded memory manager which allows C
  125.          programmers to allocate and free EMS (expanded) memory similiar to
  126.          malloc() and free() in the standard C runtime library. It requires
  127.          the use of the EMS4C library,  also  distributed  by  MarshallSoft
  128.          Computing.   Both  EMM4C  and  EMS4C  require  that your system be
  129.          configured with expanded (EMS) memory.
  130.  
  131.          The  source  code  for the EMM4C library is provided in "shrouded"
  132.          form for shareware distribution. It is distributed  in  this  form
  133.          rather   than   as   a   library   (.LIB)   file  because  of  the
  134.          inconsistancies  between  object  files  generated  by   different
  135.          compilers.  To support several compilers would require a .LIB file
  136.          for each compiler manufacturer, and sometimes several versions  of
  137.          the  .LIB  file  are needed for the different versions of the same
  138.          manufacturers compiler! This problem doesn't occur with  assembler
  139.          libraries,  which  is  why  EMS4C.LIB  can  be  used  with  all  C
  140.          compilers.
  141.  
  142.          You  can  compile this code, but you will have to register with us
  143.          in order to get the normal (commented) C source code  with  normal
  144.          variable names.
  145.  
  146.          1.1 Distribution Files
  147.  
  148.          EMM4C.H      : EMM4C prototype file.
  149.          EMM4C.C      : SHROUDED source for the EMM4C library.
  150.          EMM_TEST.C   : Source for the EMM4C test driver.
  151.          EMM_TEST._T_ : Borland C & Turbo C makefile for EMM_TEST.
  152.          EMM_TEST._M_ : Microsoft C makefile for EMM_TEST.
  153.          EMM_TEST._Q_ : Microsoft Quick C makefile for EMM_TEST.
  154.          X_EMM_T.BAT  : Batch file to make EMM_TEST with MIX Power C.
  155.          EMM4C.DOC    : Documentation file.
  156.  
  157.          Registered users also receive:
  158.  
  159.          EMM4C.C      : (Unshrouded) source code for the EMM4C library.
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.         EMM4C Users Manual                                     Page 3
  181.          1.2 Compiling the Library
  182.  
  183.  
  184.          The  EMM4C  library  is provide in "shrouded" form as discussed in
  185.          the introduction. However, it can still be compiled like any  other
  186.          source  file.  In  particular, it is compiled by the makefiles for
  187.          the test driver program EMM_TEST.C
  188.  
  189.          Registered  users can compile the unshrouded  version  of  EMM4C.C
  190.          instead.
  191.  
  192.  
  193.          1.3 User Support
  194.  
  195.  
  196.          We  want you to be successful in developing your application using
  197.          our libraries! We depend on our customers to let us know what they
  198.          need in a library.  This means we are committed to  providing  the
  199.          best  libraries  that  we  can.   If  you  have any suggestions or
  200.          comments, please write to us or give us a call.
  201.  
  202.          If  you  are having a problem using EMS4C or any of our libraries,
  203.          call (205) 881-4630 between 5 PM  and  9  PM  CST  Monday  through
  204.          Friday.  You can call at other times and leave a message, and call
  205.          back  later during our regular business hours for a reply. You can
  206.          also FAX us at this same number at any time.
  207.  
  208.          You  may  also  call our 24 hour BBS (2400 baud, no parity, 8 data
  209.          bits, 1 stop bit) at any time.  The BBS will  contain  the  latest
  210.          shareware version of EMS4C, messages, and other related files. All
  211.          files  are  in standard ZIP format. You can leave a message on the
  212.          BBS, and we will usually have a reply  ready  for  you  within  24
  213.          hours.   The dedicated telephone number is 205-880-9748.  Set your
  214.          modem for 1200 to 9600 baud, 8 data bits, no parity, one stop bit.
  215.  
  216.          The  MarshallSoft  Computing,  Inc.   newsletter  "Comm  Talk"  is
  217.          published quarterly.  It discusses various communications problems
  218.          and  solutions using PCL4C (the communications library) as well as
  219.          related information such as data compression  issues.   Registered
  220.          users  receive  a  one  year complimentary subscription when first
  221.          registering and for each update purchased.   Additional  one  year
  222.          subscriptions  are  $15  plus $5 for overseas postage (postpaid in
  223.          US).
  224.  
  225.  
  226.          1.4 ASP Ombudsman
  227.  
  228.  
  229.          MarshallSoft  Computing,  Inc.  is  a member of the Association of
  230.          Shareware Professionals (ASP).  ASP wants to make  sure  that  the
  231.          shareware principle works for you.  If you are unable to resolve a
  232.          shareware-related  problem  with  an  ASP member by contacting the
  233.          member directly, ASP may be able to help. The  ASP  Ombudsman  can
  234.          help you resolve a dispute or problem with an ASP member, but does
  235.          not provide technical support for members' products.  Please write
  236.          to  the  ASP  Ombudsman  at  545  Grover  Road,  Muskegon,  MI USA
  237.          49442-9427, Fax 616-788-2765, or send  a  CompuServe  message  via
  238.          CompuServe Mail to ASP Ombudsman 70007,3536.
  239.  
  240.         EMM4C Users Manual                                     Page 4
  241.          1.5 Installation
  242.  
  243.  
  244.          (1)  Microsoft C, Borland & Turbo C, and MIX Power C compilers are
  245.          supported. However, the code should work with most any C compiler.
  246.          Before installation of EMM4C, your C compiler  should  already  be
  247.          installed  on your system and tested. If you are not familiar with
  248.          makefiles, refer to your compiler manual. If  you  are  using  the
  249.          interactive environment for Quick C or Turbo C, be sure to compile
  250.          with the memory model corresponding to the EMS4C library used.
  251.  
  252.          (2) Make a backup  copy  of  your  distribution  disk.   Put  your
  253.          original distribution disk in a safe place.
  254.  
  255.          (3)  Create  a  work  directory  on  your work disk (normally your
  256.          harddisk). For example, to create a work directory named EMM4C, we
  257.          first log onto the work disk and then type:
  258.  
  259.                                MKDIR EMM4C
  260.  
  261.          (4)  Copy  all the files from your backup copy of the distribution
  262.          disk to your work directory.  For example, to  copy  from  the  A:
  263.          drive to your work directory, we type:
  264.  
  265.                               CD EMM4C
  266.                               COPY A:*.*
  267.  
  268.          (5)   Compile the test driver  EMM_TEST.C  and  link  with  the
  269.          appropriate EMS4C library. For example, to make EMM_TEST.EXE:
  270.  
  271.              a) Borland Turbo C: Type
  272.  
  273.                    MAKE -FEMM_TEST._T_
  274.  
  275.              b) Microsoft C: Type
  276.  
  277.                    MAKE EMM_TEST._M_
  278.  
  279.              c) Quick C: Type
  280.  
  281.                    MAKE EMM_TEST._Q_
  282.  
  283.              d) MIX Power C: Type
  284.  
  285.                    X_TEST_S
  286.  
  287.          You will need the EMS4C library and header file EMS4C.H  from  the
  288.          EMS4C distribution disk in order to compile EMM4C.C.  You may want
  289.          to install the EMM4C and EMS4C files in the same directory  rather
  290.          than separate directories. Refer to EMS4C.DOC for more information
  291.          on the EMS4C library.
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.         EMM4C Users Manual                                     Page 5
  301.          2.0 The EMM4C Library
  302.  
  303.  
  304.          The  EMM4C library is built using EMS4C and is designed to be used
  305.          like the standard C runtime library functions malloc() and free().
  306.          The only difference is that emmAlloc() returns an  integer  handle
  307.          that  is  used by emmLock() in order to map the necessary pages to
  308.          the page frames, and compute an address.
  309.  
  310.          Since a maximum of 64KB can be mapped at any one time,  regardless
  311.          of  the  amount  of  EMS  memory  allocated, not all allocated EMS
  312.          blocks can be locked at any one time. For  example,  if  you  have
  313.          allocated  four 20MB blocks with emmAlloc(), then you can lock any
  314.          three at any one time (since 3*20=60 < 64) but not  all  4  (since
  315.          4*20=80  >  64).   You  determine  which  blocks to map by calling
  316.          emmLock().
  317.  
  318.          A brief summary of functions are as follows:
  319.  
  320.          emmInit   --  Initializes EMM4C module.
  321.          emmDone   --  Terminates EMM4C module.
  322.          emmPages  --  Returns EMS allocation statistics.
  323.          emmAlloc  --  Allocates one or more paragraphs.
  324.          emmFree   --  Frees  previously allocated EMS memory.
  325.          emmLock   --  Locks an allocated EMS page(s)
  326.          emmUnlock --  Unlocks a previous locked EMS page(s).
  327.          emmError  --  Displays error text.
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.         EMM4C Users Manual                                     Page 6
  361.          3.0 EMM4C Library Functions
  362.  
  363.  
  364.                              3.1 emmInit
  365.  
  366.  
  367.         Function:    Initializes EMM module.
  368.  
  369.           Syntax:    int emmInit(Pages,Handles)
  370.                      int Pages;     /* # EMS pages to use */
  371.                      int Handles;   /* # handles to use */
  372.  
  373.          Remarks:    The emsInit() function initialized the EMM module. Two
  374.                      initialization parameters are specified.
  375.  
  376.                      <Pages>  is  the  number  of EMS pages which EMM is to
  377.                      manage. This must be less or equal to the total number
  378.                      of EMS pages available. Do not specify more EMS  pages
  379.                      than  necessary  as  other  programs  such as drivers,
  380.                      TSRs, etc. may wish to use EMS memory also.
  381.  
  382.                      <Handles> is the maximum number of EMS blocks  can  be
  383.                      allocated  at  any  one  time.  That is, the number of
  384.                      emmAlloc() calls minus the number of emmFree()  calls.
  385.                      Again,   don't   specify   more   than   needed  since
  386.                      conventional memory is used for each handle.
  387.  
  388.          Returns:    NO_ERROR: No error.
  389.                      ALREADY_INIT: EMM already initialized.
  390.                      MALLOC_FAILS: malloc() fails.
  391.                      BAD_HANDLE: Value of Handle out of range
  392.                      BAD_PAGE: Value of Page out of range.
  393.  
  394.          Example:    /* initialize */
  395.                      int Pages = 10;
  396.                      int Handles = 25;
  397.                      ...
  398.                      if((Code=emmInit(Pages,Handles))<0) emmError(Code);
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.         EMM4C Users Manual                                     Page 7
  421.                              3.2 emmDone
  422.  
  423.  
  424.         Function:    Terminates the EMM4C module.
  425.  
  426.           Syntax:    int emmDone()
  427.  
  428.          Remarks:    The emmDone() function frees all allocated EMS  pages.
  429.                      This  function  should  be  called before exiting from
  430.                      your application or else those EMS pages allocated  by
  431.                      the  EMM4C  module  are  lost  for  use  by subsequent
  432.                      programs.
  433.  
  434.                      If   you   forget   to  call  emmDone()   before  your
  435.                      application exits, you will have to reboot your system
  436.                      to regain the EMS pages which were allocated  but  not
  437.                      freed.
  438.  
  439.  
  440.          Returns:    NO_ERROR: No error.
  441.  
  442.          Example:    /* all done */
  443.                      emmDone();
  444.                      exit(0);
  445.  
  446.         See Also:    emmInit
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.         EMM4C Users Manual                                     Page 8
  481.                              3.3 emmPages
  482.  
  483.  
  484.         Function:    Returns EMS allocation statistics..
  485.  
  486.           Syntax:    int emmPages(PagesPtr,ParaPtr)
  487.                      int *PagesPtr;  /* pointer to # completely free pages */
  488.                      int *ParaPtr;   /* pointer to # free paragraphs */
  489.  
  490.          Remarks:     The emmPages function is designed to provide page and
  491.                      paragraph  allocation  statistics  to the caller.  The
  492.                      1st argument is used to return  the  number  of  pages
  493.                      which  were  set aside by emmInit() that have not been
  494.                      allocated in whole  or  part  by  emmAlloc.   The  2nd
  495.                      argument  is  used  to  return  the  total  number  of
  496.                      paragraphs  (16  byte  blocks)  anywhere   among   the
  497.                      allocated  pages.   There  is  no  statement as to the
  498.                      contiguousness of the paragraphs.
  499.  
  500.          Returns:    NO_ERROR: No error.
  501.                      NOT_INIT: EMM not initialized.
  502.  
  503.          Example:    int Code;
  504.                      unsigned int Pages;
  505.                      unsigned int Paras;
  506.                      ...
  507.                      /* get allocation statistics */
  508.                      Code = emmPages(&Pages,&Paras);
  509.                      if(Code==0)
  510.                        {printf("%u pages allocated\n",Pages);
  511.                         printf("%u paragraphs allocated\n",Paras);
  512.                        }
  513.                      else emmError(Code);
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.         EMM4C Users Manual                                     Page 9
  541.                              3.4 emmAlloc
  542.  
  543.  
  544.         Function:    Allocates one or more paragraphs.
  545.  
  546.           Syntax:    int emmAlloc(Size)
  547.                      unsigned int Size;  /* size in bytes */
  548.  
  549.          Remarks:     The emmAlloc() function allocates paragraphs (16 byte
  550.                      blocks) from the pool of pages  (1024  paragraphs  per
  551.                      page) specified in the emmInit() function call.
  552.  
  553.                      An integer refered to as a "handle" is returned, which
  554.                      is  used in subsequent call to emmLock(), emmUnlock(),
  555.                      and emmFree(). In particular, the handle must be  used
  556.                      in   calling  emmLock  to  obtain  a  pointer  to  the
  557.                      paragraphs allocated by emmAlloc().
  558.  
  559.                      If  a  series  of  emmAlloc()  and emmFree() calls are
  560.                      made, then EMS memory may become fragmented. That  is,
  561.                      the  available  remaining page paragraphs (the unit of
  562.                      allocation) may not form a contiguous block.
  563.  
  564.          Returns:    NO_ERROR: No error.
  565.                      NOT_INIT: EMM not initialized.
  566.                      NO_HANDLES: No handles remaining.
  567.                      NO_PAGES: No pages remaining.
  568.                      BAD_SIZE: Value of Size out of range.
  569.  
  570.          Example:   unsigned int Size;
  571.                      int Handle;
  572.                      ...
  573.                      Size = 50000;
  574.                      Handle = emmAlloc(Size);
  575.                      if(Handle>=0)
  576.                        {printf("%u bytes allocated to handle &d\n",
  577.                           Size,Handle);
  578.                        }
  579.                      else emmError(Code);
  580.  
  581.         See Also:    emmFree, emmLock.
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.         EMM4C Users Manual                                     Page 10
  601.                              3.5 emmFree
  602.  
  603.  
  604.         Function:    Frees  previously allocated EMS memory.
  605.  
  606.           Syntax:    int emmFree(Handle)
  607.                      int Handle;  /* handle used for previous emmAlloc */
  608.  
  609.          Remarks:    The emmFree() function is use to free EMS memory which
  610.                      was previously allocated with emmAlloc(). Once  freed,
  611.                      the  contents  of  the  (previously)  allocated blocks
  612.                      cannot be recovered (with EMM4C module calls).
  613.  
  614.                      If  a  series  of  emmAlloc()  and emmFree() calls are
  615.                      made, then EMS memory may become fragmented. That  is,
  616.                      the  available  remaining page paragraphs (the unit of
  617.                      allocation) may not form a contiguous block.
  618.  
  619.          Returns:    NO_ERROR: No error.
  620.                      NOT_INIT: EMM not initialized.
  621.                      BAD_HANDLE: Value of Handle out of range
  622.  
  623.          Example:    int Handle;
  624.                      int Code;
  625.                      ...
  626.                      Code = emmFree(Handle);
  627.                      if(Code==0) printf("Handle %d is freed\n",Handle);
  628.                      else emmError(Code);
  629.  
  630.         See Also:    emmAlloc.
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.         EMM4C Users Manual                                     Page 11
  661.                              3.6 emmLock
  662.  
  663.  
  664.         Function:    Locks an allocated EMS page(s)
  665.  
  666.           Syntax:    int emmLock(Handle,SegmentPtr)
  667.                      int Handle;       /* Handle to lock */
  668.                      char *SegmentPtr; /* pointer to segment value */
  669.  
  670.          Remarks:    The emmLock function is used to get the segment of the
  671.                      memory block referenced by the handle. The segment  is
  672.                      used  to  compute  the physical address on a paragraph
  673.                      boundary within the 4 contguous 16KB page frames.  The
  674.                      macro  MAKE_FAR_PTR  (defined  in  emm4c.h) or MAKE_FP
  675.                      (defined by many C compilers) can be used  to  compute
  676.                      the block address from the segment.
  677.  
  678.          Returns:    NO_ERROR: No error.
  679.                      NOT_INIT: EMM not initialized.
  680.                      NO_FRAMES: No (unmapped) frames remaining.
  681.                      BAD_HANDLE: Value of Handle out of range.
  682.  
  683.          Example:    int Handle;
  684.                      int Code;
  685.                      unsigned int Segment;
  686.                      char far *FarPtr;
  687.                      ...
  688.                      Code = emmLock(Handle,&Segment);
  689.                      if(Code==0)
  690.                        {FarPtr = MK_FP(Segment,0);
  691.                         ...
  692.                        }
  693.                      else emmError(Code);
  694.  
  695.         See Also:    emmUnlock
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.         EMM4C Users Manual                                     Page 12
  721.                              3.7 emmUnlock
  722.  
  723.  
  724.         Function:    Unlocks a previous locked EMS page(s).
  725.  
  726.           Syntax:    int emmUnlock(Handle)
  727.                      int Handle;
  728.  
  729.          Remarks:    The   emmUnlock()  function  is  used  to  unlock   a
  730.                      previously  locked EMS block. Recall that only 64KB of
  731.                      frame space is available.  This means that the largest
  732.                      single block that can be locked is 64KB.
  733.  
  734.                      Recall that allocations of more than 16KB always start
  735.                      on a page boundary. Thus an allocation of 16385  bytes
  736.                      (16KB  +  1  byte)  will take 1 full page plus the 1st
  737.                      paragraph of the 2nd page. A second allocation of more
  738.                      than 16KB will be allocated to a 3rd page, not the 2nd
  739.                      page.
  740.  
  741.  
  742.          Returns:    NO_ERROR: No error.
  743.                      NOT_INIT: EMM not initialized.
  744.                      BAD_HANDLE: Value of Handle out of range
  745.  
  746.          Example:    int Code;
  747.                      int Handle;
  748.                      ...
  749.                      Code = emmUnlock(Handle);
  750.                      if(Code==0) printf("Handle %d unlocked\n",Handle);
  751.                      else emmError();
  752.  
  753.         See Also:    emmLock.
  754.  
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.         EMM4C Users Manual                                     Page 13
  781.                              3.8 emmError
  782.  
  783.         Function:    Displays error text.
  784.  
  785.           Syntax:    int emmError(Code)
  786.                      int Code;  /* error Code */
  787.  
  788.          Remarks:      The  emmError()  function  is  used  to display  the
  789.                      error  text  associated  with  an EMS4S or EMS4C error
  790.                      code.  It  references  the  emsError()  routine in the
  791.                      EMS4C library.
  792.  
  793.  
  794.          Returns:    NO_ERROR: No error.
  795.  
  796.          Example:    int Code;
  797.                      ...
  798.                      Code = emmUnlock(Handle);
  799.                      if(Code==0) printf("Handle %d unlocked\n",Handle);
  800.                      else
  801.                        {
  802.                         ...
  803.                         emmError();
  804.                        }
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.         EMM4C Users Manual                                     Page 14
  841.          4.0 EMM4C Error Codes
  842.  
  843.  
  844.          Negative  error  codes  are  defined  for the EMM module (they are
  845.          different  than  the  error  codes defined for  the  EMS  module).
  846.          The error symbols are defined in EMM4C.H.
  847.  
  848.  
  849.                              EMM4C Error Codes
  850.  
  851.  
  852.          ***********************************************************
  853.          *   0  *  NO_ERROR     *  No error.                       *
  854.          *  -1  *  ALREADY_INIT *  EMM already initialized.        *
  855.          *  -2  *  NOT_INIT     *  EMM not initialized.            *
  856.          *  -3  *  NO_HANDLES   *  No handles remaining.           *
  857.          *  -4  *  NO_PAGES     *  No pages remaining.             *
  858.          *  -5  *  NO_FRAMES    *  No (unmapped) frames remaining. *
  859.          *  -6  *  MALLOC_FAILS *  malloc() fails.                 *
  860.          *  -7  *  BAD_SIZE     *  Value of Size out of range.     *
  861.          *  -8  *  BAD_HANDLE   *  Value of Handle out of range.   *
  862.          *  -9  *  BAD_PAGE     *  Value of Page out of range.     *
  863.          ***********************************************************
  864.  
  865.  
  866.  
  867.                              Cross Reference
  868.  
  869.  
  870.                     emmUnlock...................
  871.                     emmLock..................  .
  872.                     emmFree...............  .  .
  873.                     emmAlloc...........  .  .  .
  874.                     emmPages........  .  .  .  .
  875.                     emmDone......  .  .  .  .  .
  876.                     emmInit...  .  .  .  .  .  .
  877.                              .  .  .  .  .  .  .
  878.                              .  .  .  .  .  .  .
  879.          *******************************************
  880.          *  ALREADY_INIT *   X                     *
  881.          *  NOT_INIT     *         X  X  X  X  X   *
  882.          *  NO_HANDLES   *            X            *
  883.          *  NO_PAGES     *            X            *
  884.          *  NO_FRAMES    *                  X      *
  885.          *  MALLOC_FAILS *   X                     *
  886.          *  BAD_SIZE     *            X            *
  887.          *  BAD_HANDLE   *   X           X  X  X   *
  888.          *  BAD_PAGE     *   X                     *
  889.          *******************************************
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.         EMM4C Users Manual                                     Page 15
  901.          5.0 EMM4C Test Driver
  902.  
  903.  
  904.          The EMM_TEST program is the EMM4C test driver.  It  exercises  the
  905.          the  EMM4C library, allocating and freeing blocks of EMS memory in
  906.          a random sequence. It's purpose is to (1)  demonstrate  how  calls
  907.          are   made  to  the  EMM4C  functions,  and  (2)  a  test  of  the
  908.          functionality of the EMM4C library that you can perform yourself.
  909.  
  910.          The basic algorithm is as follows:
  911.  
  912.          Loop N times
  913.             Decide to allocate a new EMS block or free an existing block.
  914.                If we are going to allocate an EMS block, then
  915.                   Choose a size (in bytes) to allocate.
  916.                   Allocate the block.
  917.                   Fill the block with a "marker" byte.
  918.                If we are going to free a previously allocated block, then
  919.                   Choose a previous allocated block not yet freed.
  920.                   Verify the marker byte value.
  921.                   Free (de-allocate) the block.
  922.          End-of-Loop
  923.  
  924.          To run the test driver, type:
  925.  
  926.             EMM_TEST <Pages> <Iterations> <MinSize> <MaxSize>
  927.  
  928.          where
  929.  
  930.             <Pages>      = the number of EMS pages you wish to manage.
  931.             <Iterations> = the number of iterations of allocate / free.
  932.             <MinSize>    = the minimum allocation size.
  933.             <MaxSize>    = the maximum allocation size.
  934.  
  935.          For  example, say you have 170 pages of EMS memory in your system,
  936.          and you wish to run the test driver using 10 pages  (160  KB)  150
  937.          times,  where  all  allocations  are  between 200 and 25000 bytes.
  938.          Enter the following:
  939.  
  940.             EMM_TEST 10 150 200 25000
  941.  
  942.          To compile the test driver, use one of the provided  makefiles  as
  943.          described in the installation section.
  944.  
  945.          You can also use an integrated environment  to  compile  the  test
  946.          driver.  Place  the  following  files  in  your  project  file for
  947.          compiling for the small memory model.
  948.  
  949.                   TEST_EMM.C
  950.                   EMM4C.C
  951.                   EMS_ERR.C
  952.                   EMS4C_S.LIB
  953.  
  954.          To use another memory model, you will need to replace  EMS4C_S.LIB
  955.          with  the correct library. Refer to EMS4C.DOC file for information
  956.          about the EMS4C library.
  957.  
  958.  
  959.  
  960.         EMM4C Users Manual                                     Page 16
  961.          6.0 Legal Issues
  962.  
  963.          6.1 Registration
  964.  
  965.  
  966.          The  registered version of EMM4C is provided free of charge at the
  967.          time that the EMS4C library is registered. Notice that  the  EMM4C
  968.          library requires the EMS4C library.
  969.  
  970.  
  971.          6.2 License
  972.  
  973.  
  974.          MarshallSoft Computing, Inc. grants the registered user  of  EMM4C
  975.          the  right  to  use  the  EMM4C  library  (in  object form) in the
  976.          development  of  any  software  product  without  any   royalties.
  977.  
  978.  
  979.          6.3 Warranty
  980.  
  981.  
  982.          MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING  TO
  983.          THIS  SOFTWARE,  WHETHER  EXPRESSED  OR IMPLIED, INCLUDING BUT NOT
  984.          LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY  AND  FITNESS
  985.          FOR  A  PARTICULAR  PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY
  986.          AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING,  INC.
  987.          NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION,
  988.          OR  DELIVERY  OF  THIS  SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
  989.  
  990.          CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT  OF  THE  USE  OR
  991.          INABILITY  TO  USE  SUCH  SOFTWARE EVEN IF MARSHALLSOFT COMPUTING,
  992.          INC.  HAS BEEN ADVISED OF  THE  POSSIBILITY  OF  SUCH  DAMAGES  OR
  993.          CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY
  994.          FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO
  995.          USE  THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON
  996.          USING  THE  SOFTWARE  BEARS  ALL  RISK  AS  TO  THE  QUALITY   AND
  997.          PERFORMANCE OF THE SOFTWARE.
  998.  
  999.          Some  states  do not allow the exclusion of the limit of liability
  1000.          for consequential or incidental damages, so the  above  limitation
  1001.          may not apply to you.
  1002.  
  1003.          This  agreement  shall  be  governed  by  the laws of the State of
  1004.          Alabama and shall inure to the benefit of Marshallsoft  Computing,
  1005.          Inc.   and  any successors, administrators, heirs and assigns. Any
  1006.          action or proceeding brought by either  party  against  the  other
  1007.          arising  out of or related to this agreement shall be brought only
  1008.          in a STATE or FEDERAL COURT of competent jurisdiction  located  in
  1009.          Madison County, Alabama. The parties hereby consent to in personam
  1010.          jurisdiction of said courts.
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.         EMM4C Users Manual                                     Page 17
  1021.          7.0 Revision History
  1022.  
  1023.  
  1024.          Version 1.0 -- July 24, 1993 -- original release.
  1025.  
  1026.  
  1027.          8.0 Other MarshallSoft Computing Products for C
  1028.  
  1029.  
  1030.          Shareware  versions  of  all  MarshallSoft  Computing products are
  1031.          available on our user support BBS 205-880-9748.
  1032.  
  1033.  
  1034.          8.1 The Personal Communications Library for C
  1035.  
  1036.  
  1037.          The Personal Communications Library for the C Language (PCL4C)  is
  1038.          an  asynchronous  communications  library designed for experienced
  1039.          software  developers  programming  in  C.   Four   compilers   are
  1040.          supported:  Microsoft  Optimizing  C,  Microsoft  Quick C, Borland
  1041.          Turbo C, and MIX Power  C.   An  IBM  PC/XT/AT  or  compatible  is
  1042.          required.  The PCL features:
  1043.  
  1044.          o SMALL, COMPACT, MEDIUM & LARGE memory models.
  1045.          o 33 communications and support functions.
  1046.          o Supports PC/4 and PC/8 Digiboard.
  1047.          o Support for the high performance INS16550 UART.
  1048.          o Supports hardware (RTS/CTS) flow control.
  1049.          o Interrupt driven receiver.
  1050.          o Supports 300 baud to 115,200 baud.
  1051.          o Supports COM1, COM2, COM3, and  COM4.
  1052.          o Adjustable receive queues from 8 bytes to 32 KB.
  1053.          o Control-BREAK error exit.
  1054.          o 17 communications error conditions trapped.
  1055.          o Allows 4 ports to run concurrently.
  1056.          o Complete modem control & status.
  1057.          o Written in assembly language for small size & high speed.
  1058.          o Terminal program featuring XMODEM, YMODEM, & YMODEM-G.
  1059.  
  1060.          The Personal Communications Library for C (PCL4C) is available for
  1061.          $55  plus  $3 S&H ($6 S&H overseas). It may be ordered at the same
  1062.          time as the Personal Protocol Library for $65 plus $3.50  S&H  ($7
  1063.          overseas).
  1064.  
  1065.  
  1066.  
  1067.  
  1068.  
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.         EMM4C Users Manual                                     Page 18
  1081.          8.2 The Personal Protocol Library for C
  1082.  
  1083.  
  1084.          The  Personal  Protocol  Library  (PPL)  consist of a state driven
  1085.          library  which  implements  the  XMODEM,  XMODEM-CRC,   XMODEM-1K,
  1086.          XMODEM-G,  YMODEM,  and  YMODEM-G  file  transfer protocols.  This
  1087.          allows  the  programmer  to  run   multiple   protocol   transfers
  1088.          simultaneously while interacting with the user at the keyboard.
  1089.  
  1090.          The  Personal  Protocol Library for C (PPL4C) is available for $35
  1091.          plus $3 S&H ($6 S&H overseas). Both the Communications library and
  1092.          the Protocol library can be ordered together for $65.
  1093.  
  1094.          The PPL requires the Personal Protocol Library for  C  (PCL4C)  as
  1095.          described above.
  1096.  
  1097.          8.3 The LZW Data Compression Library for C
  1098.  
  1099.          LZW4C is an implementation of the LZW (Lempel-Ziv-Welch) algorithm
  1100.          for compressing and decompressing  data.   LZW  does  particularly
  1101.          well on text files, achieving better than a 50 % compression ratio
  1102.          for many files.
  1103.  
  1104.          The  LZW  algorithm  is  considered  to be one of the best general
  1105.          purpose algorithms available today.  The  new  high  speed  modems
  1106.          that  employ  on-the-fly  data  compression (such as MNP 5.0 & the
  1107.          V.42 bis international standard) use the LZW algorithm, as well as
  1108.          such well known utility programs such as PKZIP.
  1109.  
  1110.          The  LZW  Data Compression Library for C is available for $35 plus
  1111.          $3 S&H ($6 S&H overseas).
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.         EMM4C Users Manual                                     Page 19
  1141.  
  1142.